
MAIN
                                   Port

                  Copyright © 1993-1994 Henrik Tikanvaara
                            All rights reserved


                                   Index
                                   ~~~~~

 Copyright      Copyright, distribution terms and contact address.
 Introduction   Introduction to Port.
 Instructions   General instructions.
 Usage          Commandline usage and options.
 Preferences    Port preferences file.
 Misc stuff     Other notes.
 History        History of changes.
 Finally        Some final words.
 Other prods    Information about other things I've coded.

copyright
  This program is freeware, you may copy it on as long as there is no
charge for the program (except for small handling fees if this program is
distributed on a disk), and all of the files accompanying Port and Port
itself are unaltered and remain intact. If you desire to put Port on a
CD-ROM or in some other kind of PD-Shareware library, please contact me.
The author accepts no responsibility whatsoever regarding Port, or anything
else for that matter.
  All donations will be gladly accepted, though checks and foreign
currencies all have the problem with the banks charging monstrous fees to
convert the money to Finnish marks. So don't send 'em, you'll be wasting
your money. Finnish marks and US dollars are most welcome, as are also
letters, chocolate, beer, disks, hardware etc. Sending something along a
suggestion will have a very positive effect on its chances being done. =)

Contact addresses:

Mail:

Henrik Tikanvaara
Tikasrinne 3A
02200  Espoo
Finland

Internet:

In order of preference, only use the latter ones if you get no reply in 2
weeks. I check my email once a week.

shadowlord@brahman.nullnet.fi
sl@field.ichaos.nullnet.fi
henrik.tikanvaara@mpoli.fi

intro
  Have you ever got a textfile which had fine ASCII characters, but the
accented characters were all wrong, and the file had a ^M after each line?
You had probably found a textfile written on PC. Port translates the PC
characters to their Amiga equivalents, or at least tries to make a very
close match. It also knows how to translate a SF7 format textfile. More
than this though, you can perform many other useful functions to textfiles,
I really advise you take the time to get familiar with the different
functions. Port can be viewed as a utility similar to a GFX converter, with
the difference that it works on textfiles.

instructions
  Port can only be run from the Shell, other than that, it should be very
easy to use.  Everything in the commandline is case-sensitive.
  The commandline is organized much like in LhA. First the options which
are always prefaced by a dash, then the mode, and lastly the input and
output filenames. The output filename is optional. Check Usage for a fast
index of all different options.

usage
Port V2.00
Copyright © 1994 Henrik Tikanvaara

Usage: Port [Options] <Mode> <Source> [Dest]

  Mode                     Options
  s  SF7->Amiga            -a  ANSI strip
  p  PC ->Amiga            -b  No conversion buffer
  c  Combined              -e# Make EOLs
  S  Amiga->SF7            -i# InterNet strip (1-Note/2-Blank)
  P  Amiga->PC             -l  LhA pack output file
  l  Lowercase             -n  No endspace removal
  u  Uppercase             -p  PowerPack output file
  o  Only ASCII            -s# Spaces to tabs (Def 8)
  n  Null                  -t# Tabs to spaces (Def 8)
                           -?  Credits

  Source  The source filename to be converted.
    Dest  The optional filename for the converted text.

combined
"c"  Combined

  Decodes PC and SF7 characters to Amiga format. Useful for textfiles which
have used the SF7 character set with the PC graphics characters etc.

prefs
  Port has a preferences file, where you can specify options that you want
to be active or inactive on every conversion. If you want to override the
preferences options, it can be done by setting the option in the
commandline, with an exclamation mark following it. For example, if you
have spaces to tabs conversion on (-s), and you want to turn it off, write
"-s!". After you have modified the options file to your preference, you
must copy it to "ENV:" and "ENVARC:". If you are about to have conflicting
options, you must first turn off the option you don't want, and then
specify the other option. For example, you have specified SpacesToTabs
conversion in the preferences, but now you want to use TabsToSpaces option.
These options normally cause a conflict. In the commandline, first you have
to write "-s!" (Suppress SpacesToTabs) and only after that you can specify
"-t" (TabsToSpaces).

The following options can be specified in the preferences file:

ANSIStrip
ConversionBuffer
EndSpaceRemoval
InterNetStrip
LhAPack
MakeEOLs
PowerPackOutput
SpacesToTabs
TabsToSpaces
TempDir
TickDelay

ansistrip
  Strips all ANSI codes from the file. Both $1B,"[" and $9B are understood
as the CSI or Control Sequence Introducer.



instrip
  Strips InterNet message headers from the textfile. If "1" is specified as
the option, a text telling that a header was removed is inserted to each
place where this was done. For "2", no text is inserted, the header is
simply cut off.
  This is done in the following way:
  The input lines are scanned for starting with "From " or "Path: ". If the
found text is "Path: ", then all the following lines are cut off, until an
empty line is encountered. If the text is "From ", the line is also scanned
for numbers and colons, which should be present if the line has a time
stamp. If those conditions were fulfilled, the data is skipped until
hitting an empty line. For the "From " part, this method should work pretty
well, but the cut might accidentally be triggered if a normal line starts
with "Path: ". Use with care.

lhaoutput
  The output textfile is automatically packed with LhA. For this to work
you have to have LhA in your path.

ppoutput
  The output textfile is automatically packed using "powerpacker.library",
with best compression and largest buffer size.

tempdir
  Specifies where the temporary output textfile is written when a packing
option is selected. You should use a directory in RAM: but if you run out
of memory, you can set it somewhere else.

tickdelay
  Specifies the delay between each progress report. Actually, it specifies
the number of Vertical Blanks to wait before printing a new progress
report. For normal PAL monitors, there are 50 VBlanks in a second, so
setting this to 25 will result in 2 progress reports per second, 10 in 5
and so on. NTSC monitors have 60 per second, and multisync have something
like 70, I think. On my Amiga 1200 with fast RAM, I noticed that it doesn't
affect the conversion speed by much on values at and over 15 VBlanks (with
a monitor of 50 VBlanks per sec). A value between 15-50 is usually good for
PAL systems. Setting the option off specifies 1 progress report per second.

opt_noconvbuf
"-b"  No conversion buffer

  By default, Port reads the whole source file in memory and then converts
and writes at the same time. But in case you're short of memory, this
option makes Port read and write at the same time. This mode uses memory
based on how much you have left, but with the lower limit of 100kB.
Especially to floppy users with very little memory: use two different
devices with this, if you don't want the conversion to be unreasonably
slow. Some options don't work while this option is active.

makeeols
"-e#"  Make EOLs

  Turns a string of at least # spaces into a linefeed. This option is
useful if you saved a writer-routine's data from a demo or an intro in a
textfile. Usually the text has no linefeeds, only some 10 spaces or so
between each of the "lines". This way you can make the file much more
readable. # can be 1-99.

endspace
"-n"  No endspace removal

  By default Port removes all spaces and tabs that precede the end of the
line. These are usually invisible to the user, and are left by the writer
of the textfile by accident. Removing them shouldn't cause any harm, but it
will reduce the size of the file. In case you need the spaces or tabs in
the ends of the lines, use this option.

spacestotabs
"-s#"  Spaces to tabs

  Tells Port to convert any strings of spaces and tabs to tabs, using # as
the tabsize, in case it reduces the size of the textfile. # can be from 1
to 16. Without size specification, 8 will be used. This option is very
useful with charts and other textfiles with lots of spaces in them, because
they get a lot smaller. It's a good idea to set this on as a default in
your preferences file.

tabstospaces
"-t#"  Tabs to spaces

  Convert any tabs to spaces. Tabsize used in the textfile is specified in
#. # can be from 1 to 16. Without size specification, 8 will be used.

mode
  Mode determines what Port expects the source file to be. Since almost all
of the different character codes are used in different textfile formats,
it's not easy to know what the format is just by looking what codes are
there. So usually you should first take a look at the new textfile and
determine what computer it has been written on.

  Attention!
  Be careful when choosing your mode, if you choose a wrong mode, you can
do irreversible damage to the textfile. Simply using the other mode pair
(for example, PC->Amiga & Amiga->PC) will not be able to turn the file back
into what it was, since many characters in one character set have no
equivalents in other character sets, and those are translated to _similar_
characters. In PC->Amiga mode a PC box character might be translated to a #
sign, but when the # sign is converted back to PC, it stays as a # sign.
When I made the PC->Amiga and Amiga->PC tables, I always first tried to
find an equivalent character. If there was none, I then chose a close
match. If there was a character with an accent, but the other format had no
such character, I converted the accented character into its un-accented
form. If there was an equal character, but in different case, then I
translated into that without caring of the case. Since making the table is
pretty repetitive work, I'm sure I made some mistakes. I happily change the
translations, if you notice a mistake or have a better idea.

pctoami
"p"  PC->Amiga

  Will strip all characters under $20 except TABs, LFs and ESCs and change
all non-ASCII characters ($80-$FF) to the equivalents used on Amiga. Since
Amiga's character set differs from the one used in PC, a close match is
attempted when no equivalent exists. You should read the information about
mode.


sf7toami
"s"  SF7->Amiga

  Strips all characters under $20 except TABs, LFs and ESCs, and translates
the SF7 scands ("[{\|]}") to normal Amiga scands.

amitopc
"P"  Amiga->PC

  Adds CR's to the end of each line and translates non-ASCII characters to
their equivalents on PC. You should read the general information about
mode.

amitosf7
"S"  Amiga->SF7

  Strips all characters under $20 except TABs, LFs and ESCs, and translates
scands which have an SF7 equivalent to the special SF7 form ("[{\|]}").

lowercase
"l"  Lowercase

  Translates all characters to lowercase. IMPORTANT: This is done an Amiga
file in mind. So if you try to translate a file of some other type, only
the ASCII characters will be changed correctly, many non-ASCII characters
will be mangled.

uppercase
"u"  Uppercase

  Translates all characters to uppercase. IMPORTANT: This is done an Amiga
file in mind. So if you try to translate a file of some other type, only
the ASCII characters will be changed correctly, many non-ASCII characters
will be mangled.

onlyasc
"o"  Only ASCII

  Cuts all non-ASCII characters (ie. characters with a code higher than
$7F), and a lot of characters under $20 from the file.

null
"n"  Null

  This mode does no conversion, it only strips characters under $20 except
TABs, LFs and ESCs. Use this when you want to do special operations, like
tab conversion, on an any textfile.

source
"Source"

  This is the name of the textfile(s) which you wish to convert. If the
file has been PowerPacked, it will be automatically decrunched. You can use
wildcards, since Port uses dos.library/MatchNext() to find the files.
  If you use patterns, you can either specify no destination or the
destination must be a directory. Port does not have an "ALL" option, which
would convert all files recursively, but this can easily be accomplished by
using a couple of a bit more complex patterns. For example, first "Port -s
n #?", then "Port -s n #?/#?" and so on.

Here's a piece of the documentation for MatchFirst().

  The patterns are fairly extensive, and approximate some of the ability of
Unix/grep "regular expression" patterns. Here are the available tokens:

?       Matches a single character.
#       Matches the following expression 0 or more times.
(ab|cd) Matches any one of the items seperated by '|'.
~       Negates the following expression.  It matches all strings
        that do not match the expression (aka ~(foo) matches all
        strings that are not exactly "foo").
[abc]   Character class: matches any of the characters in the class.
[~bc]   Character class: matches any of the characters not in the
        class.
a-z     Character range (only within character classes).
%       Matches 0 characters always (useful in "(foo|bar|%)").
*       Synonym for "#?", not available by default in 2.0.  Available
        as an option that can be turned on.

"Expression" in the above table means either a single character
(ex: "#?"), or an alternation (ex: "#(ab|cd|ef)"), or a character
class (ex: "#[a-zA-Z]").                

dest
  This is the optional filename or the destination directory for the
converted text. This doesn't have to be specified, in that case the
original will be overwritten by the converted text. BEWARE! If the new
textfile comes out bigger than the original and you run out diskspace, or
some other similar error occurs, you will LOSE the file. If you are using
the "No conversion buffer" option, the file will not be overwritten.
Instead, a new file with the original name and some suffix will be used as
the destination instead.

misc
Aborting the conversion
~~~~~~~~~~~~~~~~~~~~~~~
  The conversion can be aborted most of the time by pressing ^C. When using
two different files for the source and destination, the conversion can
always be aborted. But when converting on the original textfile, the
conversion can only be aborted while Port is still reading. After it starts
writing, you have to wait until it's finished. This is done to protect the
textfile, otherwise everything would be lost.

End of conversion
~~~~~~~~~~~~~~~~~
  In the end of the conversion, Port shows some information of the
converted file compared to the original. The first number tells the change
of size in bytes, and the second one the size of the converted file as a
percentage of the original.

finalwords
  Port V2.00, based on Port V1.46, was mainly developed between 18-May-94
and 26-Jun-94 in about 90 hours of work. The source code size is currently
approximately 4000 lines.


Here are some personal hellos to my friends:

Axolotl/Capacala
Did you have cool time in England and Germany? It will be interesting to
see if more people come to Aggressive Party this year (do they have money
to set it up anyway?) but it was kind of cool with so few people and so
much space. Did alcohol have an effect? Nahh...

Breeze/Capacala
I'm still quite unsure if I'll code an intro for Ass'94. Maybe, but just
maybe.

Ged
Your new text adventure system is great, it will be very easy and a lot of
fun to make adventures for it, when it's finished.

Guru Gnosis Sahib
Did you say Base? Just a moment, I gotta go to the bathroom, fast! Damn
you, code the QWK reader soon, I won't use TIN anymore.

Otu
Always fun to have around. Hope to see some more cyberpunk stories from you
soon!

Passy/Capacala
Your demo will be cool, but I'm afraid the quality of the PC compo will be
TOUGH at Ass'94.


  I have always thought that coding is clearly an art form. There are so
many different ways to do things, some are just plain usual, some are
exceedingly witty, and some are damn wicked. Such a shame only another
coder can fully appreciate the work at that level. Anyway, I thought about
the reasons I coded Port, and why I'm putting it into distribution. It
sometimes just felt too good to be given everyone for free. But then I
noted that a lot of cool programs I use have been made by other people like
me, and they are for free too. I haven't sent money for any of them, though
I have often been pretty close to doing so. But then I realized that the
proper way to pay back is to code more good stuff since I'm able to do
that. I think this is what everyone should do. If you have done some useful
code for your own need, why don't you distribute it!


Here's a list of coders I think have done nice work:

Stefan Boberg        - LhA
Christoph Feck       - FJPEG
Holger Kruse         - ReOrg
Jarno Paananen       - S3M code
Christophe Passuello - ShowGIF


  Remember to write if you have some cool suggestions for features you'd
like Port to have, or if you happen to find a bug. In case of a bug, tell
me exactly what to do to make the bug appear, and send the textfile (or a
part of it) which causes the bug, if possible. Also describe it well, if it
isn't obvious. And write in any case if you're able; I want to know how
many people are using Port! I know it's a pain to write real letters, but
everyone can drop a note through Internet. And if you don't have email
access, get it! You can get in touch with a lot of people around the world,
for free. Why don't people use their modems to their full potential?


For my newest programs and Internet email access, call
                              ______
    ________/\________/\  /\  \    |  /\___  ___/\   /\   /\__   ___
    \        /\        /\/  \  \   | /\    \/    /  /  \  \   \ |   |
    |\  ____/ /\  ____/ /\__/\ |\  |/ |\  _  _  /| /\__/\ |\__ \|   |
    | \/  ___/\ \/     /      \| \_/  | \/|\/|\/ |/      \|   \ \__ |  
    |         /   |    \  /\   \   |  |   |  |   /   /\   \   |\   \|
    |________/|___|\___/ /  \   \__|__|___|  |__/   /  \   \__| \__ \
   **[ggs]***********\  /****\  /***************\  /****\  /*******\/*
                 _    \/      \/                 \/      \/
 -=*=- Sysop: Guru Gnosis Sahib -=*=- Co-Sysops: Shadow Lord & X-Dus -=*=-
 -=*=- AXsh v1.31 PL1 reg, 68030/25/7MB/320MB & USR 16800 DS -=*=-


                               +358-0-498797
                               ~~~~~~~~~~~~~


  //
\X/   Thanks to Amiga for being the coolest computer ever!
